home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / tools / shell-tools / wbstart / xfa_library / xfa_library.doc < prev    next >
Text File  |  1996-04-24  |  38KB  |  1,430 lines
  1. ------------------------------------------------------------------------------
  2.  
  3.                                  eXtra Fast Animation Library
  4.  
  5.                                       XFA.LIBRARY v 1.00
  6.                                         ------------------
  7.         
  8.                                         © ClassX 1995 
  9.  
  10.                                   Concept/Code/Design by Mik
  11.  
  12.                                 ...............................
  13.  
  14.                                     Written by Michele Puccini
  15.                                             of ClassX
  16.                                         Via Francesca 463
  17.                                 I-56030 Montecalvoli (PI) ITALY
  18.                                      Tel/Fax +39 587 749206
  19.  
  20.                 EMail: classx@pisoft.it (Bug-Reports, Comments, Greets)
  21.  
  22. ------------------------------------------------------------------------------
  23.  
  24.     IMPORTANT:
  25.     This library is FreeWare, and NOT FOR COMMERCIAL PUPOSES.
  26.     If you write an application that makes use of this library, you
  27.     are kindly requested to let me know and to give me one copy of
  28.     what you've developed.
  29.     This library cannot be used for commercial products without written
  30.     permission of ClassX Development Italy.
  31.  
  32. ------------------------------------------------------------------------------
  33. Standard Disclaimer
  34. *******************
  35.  
  36. THERE IS NO WARRANTY FOR THE SOFTWARE TO THE EXTENT PERMITTED BY APPLICABLE
  37. LAW.  EXCEPT WHERE OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
  38. OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
  39. EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  40. WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE
  41. ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU.
  42. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  43. SERVICING, REPAIR OR CORRECTION.
  44.  
  45. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
  46. ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE SOFTWARE
  47. AS PERMITTED BELOW, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL,
  48. SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
  49. INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR
  50. DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES
  51. OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
  52. SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  53. DAMAGES.
  54.  
  55. ------------------------------------------------------------------------------
  56.  
  57. - Another NON-STANDARD animation format, why ?
  58. Well, during the development of X-DVE, our titling/animation system, one of
  59. the first problems I had to face was to choose an animation format suited
  60. for video resolutions (meaning both PAL and NTSC) fast enough to play 
  61. smooth, even with high resolution and "deep" screens.
  62. I started to test the various standard animation formats, like Anim-5, Anim-7
  63. etc.
  64. They were all too slow to play and gave other extra features (like multiple
  65. palette handling, multi frame rates, complete multitasking) which I could 
  66. stand without.
  67. The only anim format very near to my requirements was SCALA's anim 32I, but:
  68. - there was no documentation for it.
  69. - it was smooth enough, but trying to swith caches off (68040) display
  70. started to flash, making me think of a bad double buffering tecnique.
  71. So, I decided to start working on a new compression tecnique (XFA) that
  72. now is in your hands.
  73.  
  74. - What kind of tecnique is used in XFA ?
  75. The tecnique is the classic "delta frame compression" that is normally used
  76. for anim-5, anim-7 formats.
  77.  
  78. XFA animations can be of 4 different kinds:
  79.  
  80. MODE                COMPRESSION                DISPLAY                    NOTE
  81. XFA_MODE16        16 bit                     ANY(forced to PAL)    right for disk play
  82. XFA_MODE32        32 bit                     ANY(forced to PAL)    right for disk play
  83. XFA_MODE16I     16 bit                     PAL/NTSC Lace
  84. XFA_MODE32I     32 bit                     PAL/NTSC Lace
  85.  
  86. While MODE16 and MODE32 can be played from disk and in any screen mode,
  87. MODE16I and MODE32I offers a better compression but can only be played
  88. in PAL or NTSC interlaced screens (this is what I need for VIDEO applications)
  89. The "I" modes are expressely developed to run at 50fps (PAL) and MUST run
  90. at 50fps (the only way to see smooth animations)
  91. The difference from anim-5/7 is that XFA deltas can be decompressed with a
  92. small (can be totally cached), fast and furious asm routine that outperforms
  93. any comparable standard decompression routine.
  94. Another difference is that, for "16I & 32I" modes, only half information
  95. is compressed for each frame, (nearly) doubling the decompression speed and 
  96. (nearly) halving the size of each delta.
  97. Displaying XFA "16I & 32I" mode animations, involves some low-level work
  98. with copper lists, in order to achieve a solid double buffering, even when
  99. the CPU is not fast enough to decompress deltas in synch with the vertical
  100. beam.
  101.  
  102. ------------------------------------------------------------------------------
  103. This library has been developed to allow flexible access to XFA animations.
  104. PD programmers are strongly encouraged to use this library as it has a "uman"
  105. programming approach and interesting (I hope) performances.
  106. I Hope to see talented PD programmers using this library for players,
  107. converters and other related applications.
  108. The first application I hope to see in the next months is a complete XFA
  109. datatype (........even if this will not give 50fps XFA's, it will be beautiful
  110. to have a (Multi)View of this kind of format in an intuition window !)
  111. Thank you for reading and supporting.
  112. Feel free to contact me for suggestions/improvements/questions.
  113. I MUST remember that XFA animations can be possible only thanks to Amiga
  114. custom chips and its fantastic OS (...that's the way it is, mr. big blue)
  115. Last-Last-Last:  Italy is full of great Amiga talents but I really want
  116. to make a special thank to Fabio Rotondo for writing XFA_Util 2 (no more
  117. excuses, the docs are here, now it's on you !)
  118.  
  119.  
  120.     Banner:
  121.  
  122.      // 
  123.     \X/ Amiga. Computers for Thinking people
  124.        ------------------------------------
  125.  
  126.                                                                     Michele Puccini
  127.  
  128. ******************************************************************************
  129. (sorry: No AutoDocs &| AmigaGuide this time)
  130.  
  131. **** History ****
  132.  
  133. v1.0:
  134. First release, official X-DVE 2.0 compression library
  135.  
  136.  
  137.  
  138.  
  139. **** ToDo *****
  140.  
  141. Allow the use of XFA_LibErr() to detect errors
  142.  
  143.  
  144. **** CPU-68000 WARNING ****
  145.  
  146. Developer's package includes library versions compiled for 68000/20/30/40.
  147. Animations packed with 68020+ libraries CANNOT BE PLAYED on a standard
  148. 68000 cpu, because of data alignment restrictions (you'll get an address
  149. error).
  150. So, if you want to play XFA animations on a basic 68000 Amiga, you must
  151. compress them with xfa.library for 68000 processors, that automatically
  152. generates 68000-compatible anims.
  153. Note that 68020,030,040 libraries are equivalent in size and code (I use
  154. no FPU code inside, (and no 680x0 specific code...)).
  155.  
  156.  
  157. **** EXAMPLES AND SUPPORT CODE ****
  158.  
  159. The example code is written in BlitzII which is powerful, simple and very
  160. near to C (well, not too much....).
  161. I suppose there will be no problems for C coders to read and understand it.
  162. C include files are supplied in the appropriate drawer but I've no time to
  163. give them a better "Amiga-Library-Standard" look (help will be appreciated).
  164. BlitzII include file is "LIB_XFA.BB" and must be included everytime you want
  165. to use xfa.library.
  166. For BlitzII users there is also "xfa.library1" file that MUST be put into
  167. "Blitz2:blitzlibs/amigalibs" drawer, in order to get access to xfa.library
  168. functions (DefLibs MUST also be updated with the MakeDefLibs proggie).
  169.  
  170.  
  171. **** SPEED DEMONS READ THIS ****
  172.  
  173. XFA is really an extra fast animation format and, if you believe in
  174. miracles, you will obtain 256 colours super-hires overscan 1472x566
  175. 50fps animations with pictures floating on the screen an a basic A1200 ;)
  176. This surely is the dream of everyone involved in video production.
  177. If XFA could do this, I could surely take the Nobel for Computer Science !
  178. You know that this is impossible to obtain from today's personal computers
  179. expecially if they don't have some hot chips inside.
  180. Amiga display chips, are really the best for video applications, but they
  181. have to be updated, just to follow today's users requirements.
  182. If they were light years away from the silly CGA, they now suffer of some
  183. bottlenecks (slow clock, cpu stealing, dma saturation).
  184. Now figure this:
  185. to play an animation at 50fps you have to unpack 1 frame every 1/50s.
  186. If the animation is a simple 640x512x4bpl resolution, the maximum thoughput
  187. you have to substain is 640/8 * 512 * 4 bytes per 1/50s (163840 bytes) or
  188. 8.192.000 bytes/s.
  189. If the same animation is a 768x566x8bpl resolution througput is 21.734.400
  190. bytes/s.
  191. If you have a 1472x566x8bpl maximum througput is 41.657.600 bytes/s.
  192. That's (nearly) all, but you have also to consider:
  193. - if the unpack code is in chip mem, it runs much slower than in fast
  194. - if the unpack data is in chip mem, it is accessed slower than in fast
  195. - the destination bitmaps MUST be in chip mem
  196. - the more the resolution displayed, the slower the cpu (video dma steals
  197.   cycles to cpu, and you cannot figure how much this is true in super-hires).
  198. The situation can surely improve if cpu and gfxchips have separate fast clocks
  199. and ........ but this is another story.
  200. The main point is that HOWEVER Amiga makes full screen animations possible
  201. while the others keep on dreaming in front of their waving stamp-size 160x160
  202. (pre)views.
  203.  
  204.  
  205. **** NOTE ****
  206.  
  207. This is the documentation of the functions included in xfa.library.
  208. They will surely appear to you a little bit "sparse" and sometimes
  209. lacking.
  210. Remember that xfa.libary has been developed for X-DVE, and not for you,
  211. so please accept some limitations (but feel free to ask me).
  212. These library functions are not lamer-proof. This means that parameters
  213. passed to a function are intended to be safe and consistent.
  214. This library has been tested with MungWall and Enforcer under OS 3.0, OS 3.1,
  215. OS2.0 and OS 2.1.
  216. The tecniques used in this library are completely system-friendly (except
  217. for the fast bitmap doublebuffering under OS2.0 / OS2.1: an incredible
  218. trick to change a ViewPort's BitMap using a single MrgCop (don't ask me how)).
  219. To be honest I used to peek some copper lists, but this is _for_sure_ safe
  220. even if not much smart.
  221.  
  222.                             LOOK MA' ... NO ENFORCER HITS !
  223.  
  224. Suggestion: Be OS-Friendly! OS3.0+ allows to do everything you want
  225.                 without low-level programming and headaches.
  226.  
  227.  
  228. ******************************************************************************
  229.  
  230. ------------------------------------------------------------------------------
  231.  
  232. FUNCTION:
  233.  
  234.     XFA_LibErr()
  235.  
  236. PROTO:
  237.  
  238.     LONG __asm __saveds LIBXFA_LibErr(void);
  239.  
  240. ACTION:
  241.  
  242.     Returns the error code of the last library function that caused an error.
  243.  
  244. ARGUMENTS:
  245.  
  246.  
  247. BUGS:
  248.     
  249.  
  250. NOTES:
  251.  
  252.     Not currenlty used from xfa library (maybe the next version)
  253.  
  254. ------------------------------------------------------------------------------
  255.  
  256. FUNCTION:
  257.  
  258.     XFA_PackMem_W(src0,src1,dest,size,mode)
  259.  
  260. PROTO:
  261.  
  262.     LONG __asm __saveds LIBXFA_PackMem_W(register __a0 UWORD * , register __a1 UWORD * , register __a2 UBYTE * , register __d0 LONG , register __d1 BOOL );
  263.  
  264. ACTION:
  265.  
  266.     Packs the differencies of 2 chunks of memory in XFA format (16 bit).
  267.     Returns the size of compressed memory in bytes.
  268.  
  269. ARGUMENTS:
  270.  
  271.     src0 =    pointer to source memory 0
  272.     src1 =    pointer to source memory 1
  273.     dest =    pointer to destination user-allocated memory
  274.     size =    size of "src" memory chunk to be compressed
  275.     mode =    FALSE:
  276.                 evaluate compressed size (safe! : it will not write to dest)
  277.                 TRUE:
  278.                 compress memory and write packed data to dest
  279.             
  280. BUGS:
  281.  
  282.     
  283. NOTE:
  284.  
  285.     This is low level function, not sensible to packmode set by XFA_SetPack().
  286.  
  287. ------------------------------------------------------------------------------
  288.  
  289. FUNCTION:
  290.  
  291.     XFA_PackMem_L(src0,src1,dest,size,mode)
  292.  
  293. PROTO:
  294.  
  295.     LONG __asm __saveds LIBXFA_PackMem_L(register __a0 ULONG * , register __a1 ULONG * , register __a2 UBYTE * , register __d0 LONG , register __d1 BOOL );
  296.  
  297. ACTION:
  298.  
  299.     Packs the differencies of 2 chunks of memory in XFA format (32 bit).
  300.     Returns the size of compressed memory in bytes.
  301.  
  302. ARGUMENTS:
  303.  
  304.     src0 =    pointer to source memory 0
  305.     src1 =    pointer to source memory 1
  306.     dest =    pointer to destination user-allocated memory
  307.     size =    size of "src" memory chunk to be compressed
  308.     mode =    FALSE:
  309.                 evaluate compressed size (safe! : it will not write to dest)
  310.                 TRUE:
  311.                 compress memory and write packed data to dest
  312.             
  313. BUGS:
  314.  
  315.     
  316. NOTE:
  317.  
  318.     this is low level function, not sensible to packmode set by XFA_SetPack()
  319.  
  320. ------------------------------------------------------------------------------
  321.  
  322. FUNCTION:
  323.  
  324.     XFA_PackBitMap(sbitmap0,sbitmap1,dest,mode)
  325.  
  326. PROTO:
  327.  
  328.     LONG __asm __saveds LIBXFA_PackBitMap(register __a0 struct BitMap * , register __a1 struct BitMap * , register __a2 void * , register __d0 BOOL );
  329.  
  330. ACTION:
  331.  
  332.     Packs the differencies of 2 bitmaps in XFA format according to the actual
  333.     packmode set by XFA_SetPack().
  334.     Returns the size of compressed memory in bytes.
  335.  
  336. ARGUMENTS:
  337.  
  338.     sbitmap0 =    pointer to source bitmap 0
  339.     sbitmap1 =    pointer to source bitmap 1
  340.     dest =        pointer to destination user-allocated memory
  341.     mode =        FALSE:
  342.                     evaluate compressed size (safe! : it will not write to dest)
  343.                     TRUE:
  344.                     compress memory and write packed data to dest
  345.             
  346. BUGS:
  347.  
  348.     
  349. NOTE:
  350.  
  351.     Bitmaps MUST be width/height/depth identical.
  352.  
  353. ------------------------------------------------------------------------------
  354.  
  355. FUNCTION:
  356.  
  357.     XFA_UnPackBitMap_W(bitmap,pkdata)
  358.  
  359. PROTO:
  360.  
  361.     LONG __asm LIBXFA_UnPackBitMap_W(register __a0 struct BitMap *bm, register __a1 UBYTE *pkdata);
  362.  
  363. ACTION:
  364.  
  365.     Unpacks the XFA delta pkdata into a bitmap (16 bit).
  366.     Returns the address of the next byte past the end of pkdata.
  367.     
  368. ARGUMENTS:
  369.  
  370.     bitmap =    pointer to destination bitmap
  371.     pkdata =    pointer to XFA 16 bit packed delta
  372.             
  373. BUGS:
  374.  
  375.     
  376. NOTE:
  377.  
  378.     This is low level function, not sensible to packmode set by XFA_SetPack().
  379.     Destination bitmap MUST be widht/height/depth identical of the one packed
  380.     in pkdata.
  381.  
  382. ------------------------------------------------------------------------------
  383.  
  384. FUNCTION:
  385.  
  386.     XFA_UnPackBitMap_L(bitmap,pkdata)
  387.  
  388. PROTO:
  389.  
  390.     LONG __asm LIBXFA_UnPackBitMap_L(register __a0 struct BitMap *bm, register __a1 UBYTE *pkdata);
  391.  
  392. ACTION:
  393.  
  394.     Unpacks the XFA delta pkdata into a bitmap (32 bit).
  395.     Returns the address of the next byte past the end of pkdata.
  396.     
  397. ARGUMENTS:
  398.  
  399.     bitmap =    pointer to destination bitmap
  400.     pkdata =    pointer to XFA 32 bit packed delta
  401.             
  402. BUGS:
  403.  
  404.     
  405. NOTE:
  406.  
  407.     This is low level function, not sensible to packmode set by XFA_SetPack().
  408.     Destination bitmap MUST be widht/height/depth identical of the one packed
  409.     in pkdata.
  410.  
  411. ------------------------------------------------------------------------------
  412.  
  413. FUNCTION:
  414.  
  415.     XFA_UnPackBitMap(bitmap,pkdata)
  416.  
  417. PROTO:
  418.  
  419.     LONG __asm __saveds LIBXFA_UnPackBitMap(register __a0 struct BitMap * , register __a1 void * );
  420.     Returns the address of the next byte past the end of pkdata.
  421.  
  422. ACTION:
  423.  
  424.     Unpacks the XFA delta pkdata into a bitmap according to actual packmode.
  425.     
  426. ARGUMENTS:
  427.  
  428.     bitmap =    pointer to destination bitmap
  429.     pkdata =    pointer to XFA packed delta
  430.             
  431. BUGS:
  432.  
  433.     
  434. NOTE:
  435.  
  436.     Destination bitmap MUST be widht/height/depth identical of the one packed
  437.     in pkdata.
  438.  
  439. ------------------------------------------------------------------------------
  440.  
  441. FUNCTION:
  442.  
  443.     XFA_SetPack(screen,packmode)
  444.  
  445. PROTO:
  446.  
  447.     void __asm __saveds LIBXFA_SetPack(register __a0 struct Screen * , register __d0 LONG );
  448.  
  449. ACTION:
  450.  
  451.     Sets internal memory areas according to the screen settings.
  452.     Sets the pack mode for those library functions sensible to packmode.
  453.     Fills internal XFA_Head structure according to screen settings.
  454.     Fills internal XFA_CMap structure according to screen settings.
  455.     
  456. ARGUMENTS:
  457.  
  458.     screen =        pointer to screen that will contain the frames to be packed
  459.     packmode =    XFA_MODE#? packing mode used from library functions
  460.             
  461. BUGS:
  462.  
  463.     
  464. NOTE:
  465.  
  466.     This function MUST be called before starting any compression, because
  467.     it will set all the stuff needed for packing frames.
  468.     It can be called also during the packing, just to change XFA_CMap struct
  469.     (useful to make changes to palette without affecting the frames).
  470.     Due to speed and AGA display restrictions, screen's bitmap->BytesPerRow
  471.     MUST be multiple of 8 (pixel width multipe of 64).
  472.     It is NOT safe to change compression mode or screen during the packing.
  473.  
  474. ------------------------------------------------------------------------------
  475.  
  476. FUNCTION:
  477.  
  478.     XFA_GetPackMode()
  479.  
  480. PROTO:
  481.  
  482.     LONG __asm __saveds LIBXFA_GetPackMode(void);
  483.  
  484. ACTION:
  485.  
  486.     Returns the actual packmode used by the library (XFA_MODE#?).
  487.     
  488. ARGUMENTS:
  489.  
  490.             
  491. BUGS:
  492.  
  493.     
  494. NOTE:
  495.  
  496.  
  497. ------------------------------------------------------------------------------
  498.  
  499. FUNCTION:
  500.  
  501.     XFA_OpenPackStuff()
  502.  
  503. PROTO:
  504.  
  505.     BOOL __asm __saveds LIBXFA_OpenPackStuff(void);
  506.  
  507. ACTION:
  508.  
  509.     Allocates all the stuff needed for packing a sequence of frames.
  510.     This function also tries to allocate an internal pack buffer to
  511.     speedup the packing.
  512.     Returns TRUE if allocation is OK or FALSE if something failed.
  513.     
  514. ARGUMENTS:
  515.  
  516.             
  517. BUGS:
  518.  
  519.     
  520. NOTE:
  521.  
  522.     This function returns TRUE even if the pack buffer cannot be allocated,
  523.     because this will affect only the packing speed.
  524.     So, allocation of speedup buffer is transparent, but memory-hungry Amigas
  525.     will be surely slower on packing frames.
  526.  
  527. ------------------------------------------------------------------------------
  528.  
  529. FUNCTION:
  530.  
  531.     XFA_ClosePackStuff(closemode)
  532.  
  533. PROTO:
  534.  
  535.     void __asm __saveds LIBXFA_ClosePackStuff(register __d0 LONG );
  536.  
  537. ACTION:
  538.  
  539.     Frees all the stuff allocated by XFA_OpenPackStuff, including
  540.     the eventual pack buffer.
  541.     
  542. ARGUMENTS:
  543.  
  544.     closemode =    modality for closing the animation (CLOSE_#?)
  545.             
  546. BUGS:
  547.  
  548.     
  549. NOTE:
  550.  
  551.     It is safe to call this function, even if the pack stuff is not allocated.
  552.     Actually the animation can be closed in 2 ways:
  553.     CLOSE_BLANK:
  554.         this means that, playing the animation, it will show the last two frames
  555.         completely cleared.
  556.     CLOSE_LOOP
  557.         this means that the animation can loop continuously without any
  558.         visible jumps (ex: a spinning title).
  559.     This function will not return any value, even if it would be better to
  560.     notify the user about a possible failure in packing the last 2 frames.
  561.     Note that CLOSE_LOOP mode, cannot close XFA_MODEI animations correcly when
  562.     there is a odd number of frames in memory.
  563.     The reason for this is very simple, as XFA_MODEI animations work with
  564.     screens divided in odd/even frames and to loop such animations, frames
  565.     must match odd/even sequence every loop.
  566.     An example ?:
  567.  
  568.     incorrect sequence (odd number of frames):
  569.  
  570.     frame0    frame1    frame2    frame2    frame3
  571.     odd        even        odd        even        odd
  572.  
  573.     (error, next loop you'll get another odd frame)
  574.  
  575.  
  576.     correct sequence (even number of frames):
  577.  
  578.     frame0    frame1    frame2    frame2    
  579.     odd        even        odd        even
  580.  
  581.     (ok, next loop you'll get the right odd frame)
  582.  
  583.     
  584. ------------------------------------------------------------------------------
  585.  
  586. FUNCTION:
  587.  
  588.     XFA_SetFramesArray(framesarray,numframes)
  589.  
  590. PROTO:
  591.  
  592.     void __asm __saveds LIBXFA_SetFramesArray(register __a0 struct Mem * , register __d0 LONG );
  593.  
  594. ACTION:
  595.  
  596.     Tells the library to use an extenal frames array.
  597.         
  598. ARGUMENTS:
  599.  
  600.     framesarray =    pointer to an externally allocated frames array
  601.     numframes =     number of frames that can be handled from the library
  602.                         (and the size of the frames array)
  603.             
  604. BUGS:
  605.  
  606.     
  607. NOTE:
  608.  
  609.     This function can be used if you want to have a custom frames sequence
  610.     or multiple frames sequencies in memory.
  611.     You also must take care of eventual deallocation of the frames array,
  612.     as XFA_FreeFrames cannot be used for this purpose (well, you can use it
  613.     if you allocate the frames array with AllocVec, but its is a trick and
  614.     can cause future incompatibility problems).
  615.     This function overwrites internal frames array pointer, so take care of
  616.     it, or you'll loose memory and animations.
  617.  
  618. ------------------------------------------------------------------------------
  619.  
  620. FUNCTION:
  621.  
  622.     XFA_AllocFrames(numframes)
  623.  
  624. PROTO:
  625.  
  626.     struct Mem * __asm __saveds LIBXFA_AllocFrames(register __d0 LONG );
  627.  
  628. ACTION:
  629.  
  630.     Allocates a frames array for pack or play.
  631.     Returns the (struct Mem *) pointer to the frames array or NULL if
  632.     allocation failed.
  633.         
  634. ARGUMENTS:
  635.  
  636.     numframes =     number of frames that can be handled from the library
  637.                         (and the size of the frames array)
  638.             
  639. BUGS:
  640.  
  641.     
  642. NOTE:
  643.  
  644.     It is allowed to allocate multiple frames arrays with this function,
  645.     since it does not free the currently used one.
  646.     If using this feature you MUST remember all the allocations done, in order
  647.     to free them before exiting the program.
  648.     
  649. ------------------------------------------------------------------------------
  650.  
  651. FUNCTION:
  652.  
  653.     XFA_FreeFrames()
  654.  
  655. PROTO:
  656.  
  657.     void __asm __saveds LIBXFA_FreeFrames(void);
  658.  
  659. ACTION:
  660.  
  661.     Free all the currently used animation frames (linked to frames array)
  662.     and the frames array created with XFA_AllocFrames().
  663.         
  664. ARGUMENTS:
  665.  
  666.  
  667. BUGS:
  668.  
  669.     
  670. NOTE:
  671.  
  672.     It is safe to call this, even if there is no frames array.
  673.     If you have multiple frames arrays, allocated with XFA_AllocFrames(),
  674.     you have some possibilities to free them:
  675.     suppose you have anim1 and anim2 allocated with XFA_AllocFrames()
  676.  
  677.     1)
  678.     XFA_SetFramesArray(anim1,anim1frames);
  679.     XFA_FreeFrames();
  680.  
  681.     XFA_SetFramesArray(anim2,anim2frames);
  682.     XFA_FreeFrames();
  683.  
  684.     2)
  685.     XFA_SetFramesArray(anim1,anim1frames);
  686.     XFA_FreeAnim();
  687.     FreeVec(anim1); /* yes, you can, because XFA_AllocFrames() uses AllocVec() */
  688.  
  689.     XFA_SetFramesArray(anim2,anim2frames);
  690.     XFA_FreeAnim();
  691.     FreeVec(anim2); /* yes, you can, because XFA_AllocFrames() uses AllocVec() */
  692.     
  693. ------------------------------------------------------------------------------
  694.  
  695. FUNCTION:
  696.  
  697.     XFA_FreeAnim()
  698.  
  699. PROTO:
  700.  
  701.     void __asm __saveds LIBXFA_FreeAnim(void);
  702.  
  703. ACTION:
  704.  
  705.     Frees all the currently used animation frames (linked to frames array)
  706.     but leaves the frames array allocated.
  707.         
  708. ARGUMENTS:
  709.  
  710.  
  711. BUGS:
  712.  
  713.     
  714. NOTE:
  715.  
  716.     It is safe to call this, even if there is no frames array.
  717.  
  718. ------------------------------------------------------------------------------
  719.  
  720. FUNCTION:
  721.  
  722.     XFA_AnimMem()
  723.  
  724. PROTO:
  725.  
  726.     LONG __asm __saveds LIBXFA_AnimMem(void);
  727.     
  728. ACTION:
  729.  
  730.     Returns the size in bytes of the animation currently in memory.
  731.         
  732. ARGUMENTS:
  733.  
  734.  
  735. BUGS:
  736.  
  737.     
  738. NOTE:
  739.  
  740.     It is safe to call this, even if there is no frames array.
  741.  
  742. ------------------------------------------------------------------------------
  743.  
  744. FUNCTION:
  745.  
  746.     XFA_AnimFrames()
  747.  
  748. PROTO:
  749.  
  750.     LONG __asm __saveds LIBXFA_AnimFrames(void);
  751.  
  752.  
  753. ACTION:
  754.  
  755.     Returns the size in frames of the animation currently in memory.
  756.         
  757. ARGUMENTS:
  758.  
  759.  
  760. BUGS:
  761.  
  762.     
  763. NOTE:
  764.  
  765.     It is safe to call this, even if there is no frames array.
  766.  
  767. ------------------------------------------------------------------------------
  768.  
  769. FUNCTION:
  770.  
  771.     XFA_SaveAnim(filename)
  772.  
  773. PROTO:
  774.  
  775.     LONG __asm __saveds LIBXFA_SaveAnim(register __a0 char * );
  776.     
  777. ACTION:
  778.  
  779.     Save the animation held into current frames array in IFF-XFA format.
  780.     Returns 0 if OK or iff.library error code (IFFERR_#?).
  781.             
  782. ARGUMENTS:
  783.  
  784.     filename = complete path and filename of destination file
  785.  
  786. BUGS:
  787.  
  788.     
  789. NOTE:
  790.  
  791.  
  792. ------------------------------------------------------------------------------
  793.  
  794. FUNCTION:
  795.  
  796.     XFA_LoadAnim(filename,xfa_head,xfa_cmap,mode)
  797.  
  798. PROTO:
  799.  
  800.     LONG __asm __saveds LIBXFA_LoadAnim(register __a0 char * , register __a1 struct XFA_Head * , register __a2 struct XFA_CMap * , register __d0 BOOL );
  801.     
  802. ACTION:
  803.  
  804.     Multi function IFF-XFA load routine that allows to:
  805.     - check if filename is IFF-XFA
  806.     - load an animation into frames array
  807.     - load only xfa_head and xfa_cmap from an IFF-XFA animation
  808.     Returns 0 if OK or iff.library error code (IFFERR_#?).
  809.         
  810. ARGUMENTS:
  811.  
  812.     filename =    complete path and filename of source file
  813.     xfa_head =    pointer to user's allocated XFA_Head structure
  814.                     NULL to use internal library-allocated one.
  815.     xfa_cmap =    pointer to user's allocated XFA_CMap structure
  816.                     NULL to use internal library-allocated one.
  817.     mode =        TRUE to load the whole animation
  818.                     FALSE to load only xfa_head and xfa_cmap
  819.  
  820. BUGS:
  821.  
  822.     
  823. NOTE:
  824.  
  825.     If mode = TRUE, this function replaces any animation already in memory
  826.     issuing a XFA_FreeAnim() before loading the frames.
  827.     The animation will be loaded until there is space into frames-array
  828.     or in memory.
  829.     If you don't know the size (in frames) of the animation to be loaded,
  830.     it is a good thing to first get its xfa_head and allocate enogh frames
  831.     to load it all (reading the needed amount of frames from xfa_head->NFrames).
  832.     You can easily read the palette of an xfa animation simply putting your
  833.     own XFA_CMap pointer into the right parameter, before calling XFA_LoadAnim().
  834.     Note also that current packmode can be changed from this function, even if
  835.     it fails to load an animation.
  836.  
  837. ------------------------------------------------------------------------------
  838.  
  839. FUNCTION:
  840.  
  841.     XFA_PosOnFrame(frame)
  842.  
  843. PROTO:
  844.  
  845.     void __asm __saveds LIBXFA_PosOnFrame(register __d0 LONG );
  846.  
  847. ACTION:
  848.  
  849.     Inits internal buffers for subsequential XFA_PutFrame() calls.
  850.     Returns TRUE if OK or FALSE if it cannot init buffers (no memory or frame
  851.     out of range).
  852.         
  853. ARGUMENTS:
  854.  
  855.     frame = number of frame to position to
  856.  
  857. BUGS:
  858.  
  859.     
  860. NOTE:
  861.  
  862.     Please refer to examples.
  863.  
  864. ------------------------------------------------------------------------------
  865.  
  866. FUNCTION:
  867.  
  868.     XFA_PutFrame(frame)
  869.  
  870. PROTO:
  871.  
  872.     BOOL __asm __saveds LIBXFA_PutFrame(register __d0 LONG );
  873.  
  874. ACTION:
  875.  
  876.     Compresses the frame and puts it in the frames array.
  877.     Returns TRUE if OK or FALSE if it cannot compress the frame    (no memory
  878.     or frame out of range).
  879.         
  880. ARGUMENTS:
  881.  
  882.     frame = number of frame to work on
  883.  
  884. BUGS:
  885.  
  886.     
  887. NOTE:
  888.  
  889.     This function also prepares internal buffers for a subsequential call to
  890.     XFA_PutFrame(), so there's no need to issue a XFA_PosOnFrame() for each
  891.     frame.
  892.     This can be done only with sequential frames.
  893.     To put frames into the frames array randomly, a XFA_PosOnFrame(f) must
  894.     be issued before every XFA_PutFrame(f).
  895.     If packmode if 16BitI or 32BitI, extra unused rasterlines will be cleared
  896.     automatically before compressing the frame.
  897.     This is a litte example of how to pack two sequencies of frames:
  898.  
  899.     .
  900.     .
  901.     .
  902.     c = 6
  903.     XFA_PosOnFrame(c);
  904.     /* render here */
  905.     XFA_PutFrame(c); c++;
  906.     /* render here */
  907.     XFA_PutFrame(c); c++;
  908.     /* render here */
  909.     XFA_PutFrame(c); c++;
  910.     /* render here */
  911.     XFA_PutFrame(c); c++;
  912.     /* render here */
  913.     XFA_PutFrame(c); c++;
  914.     .
  915.     .
  916.     c = 40
  917.     XFA_PosOnFrame(c);
  918.     /* render here */
  919.     XFA_PutFrame(c); c++;
  920.     /* render here */
  921.     XFA_PutFrame(c); c++;
  922.     /* render here */
  923.     XFA_PutFrame(c); c++;
  924.     /* render here */
  925.     XFA_PutFrame(c); c++;
  926.     /* render here */
  927.     XFA_PutFrame(c); c++;
  928.     .
  929.     .
  930.  
  931.     Please refer to examples.
  932.  
  933. ------------------------------------------------------------------------------
  934.  
  935. FUNCTION:
  936.  
  937.     XFA_PutSkip(frame)
  938.  
  939. PROTO:
  940.  
  941.     BOOL __asm __saveds LIBXFA_PutSkip(register __d0 LONG );
  942.  
  943. ACTION:
  944.  
  945.     Puts a skip (no delta information) frame into the frames array.
  946.     Frees any other previous information in that frames array position.
  947.     Returns TRUE if OK or FALSE if it fails (no memory or frame out of
  948.     range).
  949.         
  950. ARGUMENTS:
  951.  
  952.     frame = number of frame to work on
  953.  
  954. BUGS:
  955.  
  956.     
  957. NOTE:
  958.  
  959.     This function is used internally by X-DVE but can be useful to    init all
  960.     the frames array with the predefined skip value for current pack screen.
  961.     As definition, a skip frame will be ignored during decompression, even
  962.     if it will be considered for timings as a delay of 1/50 of sec (1/60
  963.     for NTSC).
  964.  
  965. ------------------------------------------------------------------------------
  966.  
  967. FUNCTION:
  968.  
  969.     XFA_IsSkip(frame)
  970.  
  971. PROTO:
  972.  
  973.     BOOL __asm __saveds LIBXFA_IsSkip(register __d0 LONG );
  974.  
  975. ACTION:
  976.  
  977.     Returns TRUE if the frame is a skip (ignore, no delta information) one.
  978.         
  979. ARGUMENTS:
  980.  
  981.     frame = number of frame to work on
  982.  
  983. BUGS:
  984.  
  985.     
  986. NOTE:
  987.  
  988.     This function is used internally from X-DVE.
  989.  
  990. ------------------------------------------------------------------------------
  991.  
  992. FUNCTION:
  993.  
  994.     XFA_Play(loop,autopause,waitstart)
  995.  
  996. PROTO:
  997.  
  998.     BOOL __asm __saveds LIBXFA_Play(register __d0 BOOL , register __d1 BOOL , register __d2 BOOL );
  999.  
  1000. ACTION:
  1001.  
  1002.     Executes the animation stored in the frames array.
  1003.     Returns TRUE if ok or (only under OS3.0+) FALSE if it cannot allocate
  1004.     the required DBufInfo structure.
  1005.         
  1006. ARGUMENTS:
  1007.  
  1008.     loop =        Infinite loop mode.
  1009.                     TRUE: does an infinite loop play.
  1010.                     FALSE: does a single shot play.
  1011.  
  1012.     autopause = Pause mode.
  1013.                     TRUE: pauses the animation automatically everytime there are
  1014.                     no objects moving on the screen.
  1015.                     FALSE: executes the animation respecting the real animation
  1016.                     timings.
  1017.  
  1018.     waitstart =    User start mode.
  1019.                     TRUE: start to play only when the user clicks and releases
  1020.                     the left mouse button.
  1021.                     FALSE: starts to play immediately, without waiting.
  1022.  
  1023. BUGS:
  1024.  
  1025.     
  1026. NOTE:
  1027.  
  1028.     This function temporarily disables all the multitasking facilities of
  1029.     Amiga Operating System: Use with care.
  1030.     During the play, mouse buttons can be used as follows:
  1031.     Left Mouse Button:    start the animation
  1032.                                 restart from an autopause
  1033.                                 if autopause = false : pause execution until release
  1034.     Right Mouse Button:    exit the animation if in autopause
  1035.                                 if autopause = false and Left Mouse Button : exit the
  1036.                                 animation
  1037.  
  1038.     Rather complex to explain, intuitive during play.
  1039.  
  1040. ------------------------------------------------------------------------------
  1041.  
  1042. FUNCTION:
  1043.  
  1044.     XFA_UseHead(xfa_head)
  1045.  
  1046.  
  1047. PROTO:
  1048.  
  1049.     void __asm __saveds LIBXFA_UseHead(register __a0 struct XFA_Head * );
  1050.  
  1051. ACTION:
  1052.  
  1053.     'Uses' the supplied xfa_head settings.
  1054.         
  1055. ARGUMENTS:
  1056.  
  1057.     xfa_head =    pointer to user's XFA_Head structure
  1058.                     if NULL, use internally handled structure.
  1059.  
  1060. BUGS:
  1061.  
  1062.     
  1063. NOTE:
  1064.  
  1065.     This function is here for completeness, and can be modified in the next
  1066.     issues of the library.
  1067.     Actually it simply sets internal packmode according to XFA_Head.Flags
  1068.     bits.
  1069.     However, it can be used when you have multiple XFA_Head structures to refer
  1070.     to.
  1071.  
  1072. ------------------------------------------------------------------------------
  1073.  
  1074. FUNCTION:
  1075.  
  1076.     XFA_UseCMap(screen,xfa_cmap)
  1077.  
  1078. PROTO:
  1079.  
  1080.     void __asm __saveds LIBXFA_UseCMap(register __a0 struct Screen * , register __a1 struct XFA_CMap * );
  1081.  
  1082. ACTION:
  1083.  
  1084.     'Uses' supplied xfa_cmap settings on the screen.
  1085.         
  1086. ARGUMENTS:
  1087.  
  1088.     screen =     pointer to user's screen where XFA_CMap must be applied
  1089.                     if NULL, use destination XFA_SetPack() screen.
  1090.  
  1091.     xfa_cmap =    pointer to user's XFA_CMap structure
  1092.                     if NULL, use internally handled structure.
  1093.  
  1094. BUGS:
  1095.  
  1096.     
  1097. NOTE:
  1098.  
  1099.     This function is here for completeness, and can be modified in the next
  1100.     issues of the library.
  1101.     Actually it simply applies the palette in XFA_CMap to the screen.
  1102.     It is safe only to call this function inside a XFA_OpenPackStuff() - 
  1103.     XFA_ClosePackStuff(), and you must take care if the destination screen
  1104.     is opened.
  1105.     
  1106. ------------------------------------------------------------------------------
  1107.  
  1108. FUNCTION:
  1109.  
  1110.     XFA_OpenPlayStuff(wbmodeid)
  1111.  
  1112. PROTO:
  1113.  
  1114.     BOOL __asm __saveds LIBXFA_OpenPlayStuff(DREG0 BOOL wbmodeid);
  1115.  
  1116. ACTION:
  1117.  
  1118.     Allocates and inits all the stuff needed to play a sequence of frames,
  1119.     referring to the settings in XFA_Head, XFA_CMap internal structures.
  1120.     Returns TRUE if OK or FALSE if function fails to open the play screen
  1121.     and double buffering bitmaps.
  1122.             
  1123. ARGUMENTS:
  1124.  
  1125.     wbmodeid =    force a wb-like screen
  1126.                     TRUE: open play stuff forcing the output on a workbench-like
  1127.                     mode id.
  1128.                     FALSE: open play stuff forcing the output on a PAL screen.
  1129.  
  1130. BUGS:
  1131.  
  1132.     
  1133. NOTE:
  1134.  
  1135.     This function fails if there is not enough memory to allocate the
  1136.     required play stuff.
  1137.     Forcing a wb-like screen, can be useful for viewing animations on Amigas
  1138.     that cannot display PAL videomodes (attached to a VGA only monitor,for
  1139.     example).
  1140.     This means that xfa animations will be played according to wb display
  1141.     refresh frequency and overscan, but they may appear too much fast and
  1142.     sometimes out of the display clip boundaries.
  1143.     Under OS 3.0+ this function uses the BestModeID() when forcing a wb-like
  1144.     mode, while OS 2.0+ users (upgrade your OS !) will sometimes get worse
  1145.     results (have you upgraded ?).
  1146.     It is NOT safe to call this function if internal library-allocated XFA_Head
  1147.     and XFA_CMap structures are not correctly initialized.
  1148.  
  1149. ------------------------------------------------------------------------------
  1150.  
  1151. FUNCTION:
  1152.  
  1153.     XFA_ClosePlayStuff()
  1154.  
  1155. PROTO:
  1156.  
  1157.     void __asm __saveds LIBXFA_ClosePlayStuff(void);
  1158.  
  1159. ACTION:
  1160.  
  1161.     Frees all the stuff opened by XFA_OpenPlayStuff().
  1162.         
  1163. ARGUMENTS:
  1164.  
  1165.  
  1166. BUGS:
  1167.  
  1168.     
  1169. NOTE:
  1170.  
  1171.     It is safe to call this function, even if play stuff does not exist.
  1172.     
  1173. ------------------------------------------------------------------------------
  1174.  
  1175. FUNCTION:
  1176.  
  1177.     XFA_HeadPtr()
  1178.  
  1179. PROTO:
  1180.  
  1181.     struct XFA_Head * __asm __saveds LIBXFA_HeadPtr(void);
  1182.  
  1183. ACTION:
  1184.  
  1185.     Returns the internal library-allocated XFA_Head structure pointer.
  1186.         
  1187. ARGUMENTS:
  1188.  
  1189.  
  1190. BUGS:
  1191.  
  1192.     
  1193. NOTE:
  1194.  
  1195.     Useful to READ XFA_Head settings (WRITING into this structure is really
  1196.     dangerous, expecially having already an animation in memory).
  1197.     
  1198. ------------------------------------------------------------------------------
  1199.  
  1200. FUNCTION:
  1201.  
  1202.     XFA_CMapPtr()
  1203.  
  1204. PROTO:
  1205.  
  1206.     struct XFA_CMap * __asm __saveds LIBXFA_CMapPtr(void);
  1207.  
  1208. ACTION:
  1209.  
  1210.     Returns the internal library-allocated XFA_CMap structure pointer.
  1211.         
  1212. ARGUMENTS:
  1213.  
  1214.  
  1215. BUGS:
  1216.  
  1217.     
  1218. NOTE:
  1219.  
  1220.     Useful to READ XFA_CMap settings (WRITING into this structure is not 
  1221.     too dangerous, but can be easily avoided in order to change animation's
  1222.     palette. See XFA_SetPack() function).
  1223.         
  1224. ------------------------------------------------------------------------------
  1225.  
  1226. FUNCTION:
  1227.  
  1228.     XFA_ChangePackBitMap(bitmap)
  1229.  
  1230. PROTO:
  1231.  
  1232.     void __asm __saveds LIBXFA_ChangePackBitMap(register __a0 struct BitMap * );
  1233.  
  1234. ACTION:
  1235.  
  1236.     Changes the internal source bitmap pointer which PosOnFrame(), PutFrame(),
  1237.     PutSeqFrame() refer for packing a frame.
  1238.             
  1239. ARGUMENTS:
  1240.  
  1241.     bitmap =        pointer to the new source bitmap
  1242.  
  1243. BUGS:
  1244.  
  1245.     
  1246. NOTE:
  1247.  
  1248.     This function is here to allow the packing of double (or more) buffered
  1249.     animations (like Anim5/7/x) whose frames must be unpacked into 2 different
  1250.     bitmaps (one for the even, one for the odd frame).
  1251.     Please, refer to the examples.
  1252.         
  1253. ------------------------------------------------------------------------------
  1254.  
  1255. FUNCTION:
  1256.  
  1257.     XFA_PutSeqFrame(frame)
  1258.  
  1259. PROTO:
  1260.  
  1261.     BOOL __asm __saveds LIBXFA_PutSeqFrame(register __d0 LONG );
  1262.  
  1263. ACTION:
  1264.  
  1265.     Compresses the frame and puts it in the frames array.
  1266.     Returns TRUE if OK or FALSE if it cannot compress the frame    (no memory
  1267.     or frame out of range).
  1268.         
  1269. ARGUMENTS:
  1270.  
  1271.     frame = number of frame to work on
  1272.  
  1273. BUGS:
  1274.  
  1275.     
  1276. NOTE:
  1277.     
  1278.     The differencies from XFA_PutFrame() ?
  1279.     XFA_PutFrame() in conjunction with XFA_PosOnFrame() allows easy random
  1280.     access for packing xfa animations.
  1281.     This function is here to help the handling of sequential-only problems
  1282.     like anim5/7/x to xfa conversions.
  1283.     XFA_PutFrame() does some undesired stuff that is both unuseful and
  1284.     incorrect to solve the above problem, so that's why XFA_PutSeqFrame()
  1285.     is here.
  1286.     XFA_PutSeqFrame() keeps track of the previous odd/even frames automatically,
  1287.     so there's no need for the users to do this.
  1288.     This function also prepares internal buffers for a subsequential call to
  1289.     XFA_PutSeqFrame(), so there's no need to issue a XFA_PosOnFrame() for each
  1290.     frame.
  1291.     If packmode if 16BitI or 32BitI, extra unused rasterlines will be cleared
  1292.     automatically before compressing the frame.
  1293.     Please refer to examples.
  1294.  
  1295. ------------------------------------------------------------------------------
  1296.  
  1297. FUNCTION:
  1298.  
  1299.     XFA_SaveScreen(screen,filename)
  1300.  
  1301. PROTO:
  1302.  
  1303.     LONG __asm __saveds LIBXFA_SaveScreen(register __a0 struct Screen * , register __a1 char * );
  1304.  
  1305. ACTION:
  1306.  
  1307.     Saves a standard Amiga screen in IFF-ILBM format.
  1308.     Returns 0 if OK or iff.library error code (IFFERR_#?).
  1309.         
  1310. ARGUMENTS:
  1311.  
  1312.     screen =        pointer to the screen to save
  1313.     filename =    name of the iff file to write
  1314.  
  1315. BUGS:
  1316.  
  1317.     
  1318. NOTE:
  1319.  
  1320.     This function is here for completeness.
  1321.     IFF-ILBM write code is the one furnished from CBM in NewIff39 archive.
  1322.     For this reason, I don't know if it's fully bug free or not.
  1323.     If you have faith in Carolynn Scheppner, the mother of all ilbm
  1324.     handlers .........
  1325.     
  1326. ------------------------------------------------------------------------------
  1327.  
  1328. FUNCTION:
  1329.  
  1330.     XFA_OpenRead(filename,head,cmap)
  1331.  
  1332. PROTO:
  1333.  
  1334.     struct IFFHandle * __asm __saveds LIBXFA_OpenRead(register __a0 char * , register __a1 struct XFA_Head * , register __a2 struct XFA_CMap * );
  1335.  
  1336. ACTION:
  1337.  
  1338.     This function performs the following actions:
  1339.     - opens an XFA file for reading.
  1340.     - (if file is xfa) loads XFA_Head and XFA_Cmap chunks.
  1341.     - (if file is xfa) sets current packmode for library functions.
  1342.     
  1343.     Returns a pointer to an IFFHandle struct.
  1344.     Returns NULL if it fails to open the file or if the file is not xfa.
  1345.         
  1346. ARGUMENTS:
  1347.  
  1348.     filename =    complete path and filename of source xfa file
  1349.     xfa_head =    pointer to user's allocated XFA_Head structure
  1350.                     NULL to use internal library-allocated one.
  1351.     xfa_cmap =    pointer to user's allocated XFA_CMap structure
  1352.                     NULL to use internal library-allocated one.
  1353.  
  1354. BUGS:
  1355.  
  1356.     
  1357. NOTE:
  1358.  
  1359. ------------------------------------------------------------------------------
  1360.  
  1361. FUNCTION:
  1362.  
  1363.     XFA_ReadFrame(iff,mem)
  1364.  
  1365. PROTO:
  1366.  
  1367.     LONG __asm __saveds LIBXFA_ReadFrame(register __a0 struct IFFHandle * , register __a1 struct Mem * );
  1368.  
  1369. ACTION:
  1370.  
  1371.     Reads a single xfa frame from the stream allocating enough ram to store it.
  1372.     Returns 0 if OK or iff.library error code (IFFERR_#?).
  1373.         
  1374. ARGUMENTS:
  1375.  
  1376.     iff     =    pointer to a valid IFFHandle (possibly opened with XFA_OpenRead())
  1377.     mem    =    pointer to a previously allocated mem structure where this function
  1378.                 will set all appropriate fields.
  1379.  
  1380. BUGS:
  1381.  
  1382.     
  1383. NOTE:
  1384.  
  1385.     This function allocates memory, so take care of freeing every loaded
  1386.     frame as soon as you've used it.
  1387.  
  1388. ------------------------------------------------------------------------------
  1389.  
  1390. FUNCTION:
  1391.  
  1392.     XFA_FreeFrame(mem)
  1393.  
  1394. PROTO:
  1395.  
  1396.     void __asm __saveds LIBXFA_FreeFrame(register __a0 struct Mem * );
  1397.  
  1398. ACTION:
  1399.  
  1400.     Frees a single xfa frame from memory
  1401.         
  1402. ARGUMENTS:
  1403.  
  1404.     mem    =    pointer to a previously allocated mem structure indicating the
  1405.                 frame in memory.
  1406.  
  1407. BUGS:
  1408.  
  1409.     
  1410. NOTE:
  1411.  
  1412.     As Mem structure will probabily grow or change, you are kindly requested
  1413.     to make use of this function instead of trying to free frames with your
  1414.     own code.
  1415.     This will ensure future compatibility with new releases of xfa.library.
  1416.     Internal sanity check covers only NULL mem->Ptr fields, but I have to remind
  1417.     you that all arguments are intended to be safe and consistent.
  1418.  
  1419. ------------------------------------------------------------------------------
  1420.  
  1421.  
  1422. ------------------------------------------------------------------------------
  1423. LAST MINUTE CHANGES
  1424. - Added support for NTSC screens.
  1425. - Added OSCAN_VIDEO flag to OpenPlayStuff() code.
  1426. - current version is 1.10.
  1427. ------------------------------------------------------------------------------
  1428.  
  1429. <EOF>
  1430.